OpenAI Codex로 하는 하네스 엔지니어링 실습 요약

OpenAI Codex CLI와 Superpowers 플러그인을 활용하여, 하네스 엔지니어링 원칙(브레인스토밍→설계 문서→서브에이전트 TDD→컴파운드 학습→보안 점검→워크트리 정리)을 단일 프로젝트에서 단계별로 적용하는 실전 워크플로를 다룬다.

0. 사전 필수 용어 (선행지식)

본 주제를 이해하기 전에 아래 5개 용어를 먼저 숙지한다.

• 하네스 엔지니어링 (Harness Engineering) — AI 에이전트가 임의로 결과물을 변형하지 못하도록 제약·예시·흐름 제어를 체계적으로 주입하는 기법. 본 강의 전반(§1~§5)에서 실습 대상이 되는 핵심 주제다.
• AGENTS.md / CLAUDE.md — AI 에이전트에게 환경·경로·도메인 정책·작업 원칙 등을 전달하는 설정 파일. AGENTS.md는 모든 에이전트 공통 SSOT이며, CLAUDE.md는 Claude Code 전용 추가 룰을 담는다. §3, §4에서 디렉토리 구조 예시로 등장한다.
• Skill — 특정 워크플로(브레인스토밍·계획 작성·TDD 구현·보안 점검 등)를 캡슐화한 재사용 가능 단위. Superpowers·gstack·Oh My Codex 등이 Skills 묶음을 제공한다. §4, §5에서 /brainstorming, /writing-plans, /cso 등의 이름으로 호출된다.
• Subagent — 메인 에이전트가 특정 태스크를 위임하는 격리된 컨텍스트 내 에이전트. 병렬 Git Worktree와 결합하여 여러 태스크를 동시에 처리한다. §4에서 가우스·라이프니츠·칼슨 등의 이름으로 등장한다.
• OpenAI Codex CLI — OpenAI가 제공하는 AI 코딩 에이전트 CLI 및 데스크톱 앱. codex 명령 또는 GUI로 GPT-5.5 모델에 접근하고, 플러그인(Skills) 생태계를 통해 하네스를 구성한다. §4 Step 1에서 설치·설정이 시작된다.

선행지식이 부족하면 Anthropic Building Effective Agents 또는 OpenAI Codex 공식 문서를 먼저 참고한다.

1. 주제 정의

하네스 엔지니어링은 AI 코딩 에이전트가 동일 프롬프트에서도 매번 다른 결과를 내놓는 비결정성 문제를 완화하기 위해, 에이전트의 입·출력 경로에 제약·예시·역할·검토 게이트를 삽입하는 소프트웨어 엔지니어링 패턴이다. 핵심 아이디어는 "에이전트를 신뢰하는 대신, 에이전트가 따를 구조를 신뢰한다"는 원칙에 있다.

2. 풀려는 문제

하네스 엔지니어링이 다루는 4가지 시나리오:

1. 일관성 부재 — 동일 요청에서도 코드 구조·네이밍·패키지 선택이 매 실행마다 달라진다.
2. 컨텍스트 붕괴 — 긴 대화에서 컨텍스트가 자동 압축되면서 초기 요구사항 손실이 발생한다.
3. 보안·품질 게이트 없음 — 에이전트가 생성한 코드에 대한 리뷰·보안 점검이 수동으로만 진행된다.
4. 실수 반복 — 에이전트가 동일 버그·아키텍처 실수를 세션 간에 반복하고 누적 학습이 없다.

3. 핵심 개념·구조

구성 요소

워크플로 다이어그램

사용자 프롬프트
      │
      ▼
[하네스 시작]
      │
      ├─1─▶ Superpowers /brainstorming ──▶ 기획 구체화 (Q&A)
      │
      ├─2─▶ Superpowers /writing-plans ──▶ 설계 문서 (SSOT)
      │           ↕ 사용자 검토·수정
      │
      ├─3─▶ /subagent-driven-development
      │         ├─ Git Worktree 생성
      │         ├─ Subagent A (구현) → TDD
      │         └─ Subagent B (리뷰) → Approve/Reject
      │
      ├─4─▶ Compound Engineering
      │         └─ 실수 목록 → docs/ 저장 → 다음 사이클 참조
      │
      └─5─▶ gstack /cso (보안 점검) ──▶ 체크리스트 출력
                                               │
                                        Worktree 정리

4. 구현 가이드 (Do It Yourself)

시작 전 (Before you begin)

선수 조건: - OpenAI Codex 데스크톱 앱 설치 완료 - OpenAI 계정 및 구독 (GPT-5.5 접근 가능 티어) - Git 설치 (Git Worktree 사용) - 작업용 빈 프로젝트 폴더 준비

소요 시간: 최초 설정 15~30분 / 실제 프로젝트 적용 시 1~4시간

Step 1. Codex 환경 설정

목표: Codex 데스크톱 앱에서 GPT-5.5 모델로 새 프로젝트를 생성한다.

1. Codex 앱을 열고 새 채팅을 클릭한다.
2. 모델 선택에서 GPT-5.5를 선택한다.
3. 인텔리전스(Effort Level)를 "중간"으로 설정한다.

💡 실무 노하우: 인텔리전스를 처음부터 "매우 높음"으로 설정할 필요는 없다. "중간"으로 시작하고, 복잡한 설계 문서 작성이나 보안 점검 단계에서만 높임으로써 토큰 비용을 절감한다.

1. "속도형" 옵션을 활성화한다 (번개 아이콘 확인).
2. 권한을 "자동 검토"로 설정한다 (위험 권한 제외 자동 승인).
3. "새 프로젝트 추가"에서 작업 폴더를 선택하고 프로젝트 이름을 입력한다.

✅ 확인: 왼쪽 사이드바에 프로젝트 이름이 표시되면 완료.

Step 2. Superpowers 플러그인 설치

목표: 브레인스토밍·계획·TDD·리뷰 Skills를 포함한 Superpowers를 설치한다.

1. Codex 앱 내 "플러그인" 메뉴로 이동한다.
2. "Superpowers"를 검색하고 설치한다.

# Codex 채팅에서 설치 확인 방법
/superpowers

✅ 확인: /brainstorming, /writing-plans, /subagent-driven-development, /code-review 등의 Skills가 활성화되는지 확인한다.

⚠️ 주의: Superpowers는 각 단계마다 LLM 호출을 추가로 수행하므로 토큰 소모가 일반 대화 대비 3~5배 높다. 프로젝트 시작 전 주간 한도를 확인한다.

Step 3. 브레인스토밍으로 초기 기획 구체화

목표: 모호한 아이디어를 에이전트가 구체적인 기술 스택·기능 목록으로 정제한다.

1. 채팅 입력창에 초기 프롬프트를 입력한다 (의도만 전달, 기술 스택은 에이전트에게 위임):

나는 데스크톱 프로그램 사용 시간 관리 앱을 만들려고 해.
내가 Codex 같은 사이트에 들어 있으면 생산적인 일을 하는 것이고
유튜브나 인스타그램을 보고 있으면 비생산적인 일을 하고 있는 거야.
나중에 맥에서도 출시하려고 하는데 이번에는 윈도우즈 먼저 만들고 싶어.

1. 에이전트가 /brainstorming을 자동 선택했는지 확인한다.
2. 에이전트의 질문에 구체적으로 답한다:
3. 기능 범위: "사용 시간 기록만 해 줘."
4. 브라우저 처리: "브라우저 안에서는 사이트까지 구분해야 할 것 같아."
5. 사용자 설정: "생산적 분류를 나중에 내가 직접 커스터마이징 가능하게 해 줘."

💡 실무 노하우: 브레인스토밍은 "개떡같이 쓴" 프롬프트를 "찰떡같이" 바꿔주는 단계다. 기술 스택(Tauri + React + Rust 등)을 직접 지정하지 말고 에이전트의 제안을 검토한 뒤 조정한다.

✅ 확인: 에이전트가 Tauri + React + Rust 등 구체적인 기술 스택과 기능 목록을 제시하면 완료.

Step 4. 설계 문서(SSOT) 검토

목표: 에이전트가 작성한 설계 문서를 SSOT로 확정하고, 이후 모든 변경은 설계 문서를 기준으로 한다.

1. /writing-plans Skills가 실행되어 superpowers/specs/ 폴더에 설계 문서가 생성되는지 확인한다.
2. 설계 문서에 다음 항목이 포함되었는지 검토한다:
3. 기능 목록 (Functional Requirements)
4. 에러 핸들링 정책 (Error Handling)
5. 테스트 전략 (Test Strategy)
6. Fallback 처리 (예: Chrome domain 추정 실패 → neutral로 기록)

# 설계 문서 한글화 요청 예시
영어로 작성해 줘. 나 읽기 쉽게 한글 번역본도 준비해 줘.

⚠️ 주의: 에이전트가 생성하는 코드는 지속적으로 변경된다. 설계 문서를 SSOT로 삼고, 기능 변경 시에는 반드시 설계 문서를 먼저 수정한 뒤 코드 변경을 요청한다. 코드만 믿지 않는다.

✅ 확인: 설계 문서가 superpowers/specs/YYYY-MM-DD-<프로젝트명>.md로 커밋되면 완료.

Step 5. 서브에이전트 기반 TDD 구현

목표: 메인 에이전트가 서브에이전트에게 태스크를 위임하고, Git Worktree로 병렬 작업을 수행하며, 리뷰 게이트를 통과한 코드만 병합한다.

1. 구현 시작 명령을 입력한다:

서브에이전트 드리븐으로 태스크별 별도 작업자 붙여 구현하고
각 태스크 후에 메인이 리뷰한다.

1. 에이전트가 Git Worktree를 생성하는지 확인한다:

# Worktree 생성 예시 (에이전트가 자동 실행)
git worktree add worktrees/mvp -b feature/mvp

1. Git 관련 권한 요청이 오면 "앞으로 똑같은 거 있으면 묻지 마"를 선택하여 반복 승인을 줄인다.
2. 서브에이전트(예: 가우스)가 받는 프롬프트를 확인하여 메인 에이전트의 위임 패턴을 학습한다.
3. 리뷰 서브에이전트(예: 라이프니츠)가 Approve/Reject를 반환하는지 확인한다.

💡 실무 노하우: TDD 흐름에서 테스트가 의도대로 "실패"하는 것을 먼저 확인한 뒤 구현을 진행한다. "테스트가 처음부터 통과"하면 테스트가 제 역할을 못 하고 있다는 신호다.

✅ 확인: worktrees/ 폴더에 병렬 브랜치가 생성되고, 각 태스크 완료 시 Approve 메시지가 출력되면 완료.

Step 6. 컴파운드 엔지니어링 추가

목표: 리뷰 사이클에서 발생한 실수를 자동으로 docs/ 폴더에 누적하여 에이전트가 다음 사이클에서 같은 실수를 반복하지 않도록 한다.

1. 슈퍼파워스 워크플로에 컴파운드 과정을 추가하도록 지시한다:

슈퍼파워스 마지막 단계에서 리뷰 끝날 때 컴파운드 과정을 추가해서
실행 검토 사이클에서 발생했던 실수 요인들을 반복하지 않게 과정에 추가해줘.

1. docs/ 폴더에 실수 목록 문서(예: lessons-learned.md)가 생성되는지 확인한다.
2. 이후 계획 단계에서 에이전트가 이 문서를 참조하는지 관찰한다.

💡 실무 노하우: 컨텍스트 압축이 발생하더라도 docs/ 폴더의 실수 목록은 파일로 유지되므로 정보가 보존된다. 이것이 컴파운드 엔지니어링의 핵심 가치다.

✅ 확인: docs/lessons-learned.md (또는 유사 파일)가 커밋되고, 다음 태스크에서 에이전트가 이를 참조하면 완료.

Step 7. gstack CSO 보안 점검

목표: gstack 플러그인의 /cso 스킬로 코드베이스를 보안 점검하고 체크리스트를 확보한다.

1. 새 채팅을 열고 gstack 플러그인을 설치한다:

https://github.com/garrytan/gstack 이거 설치해서 /cso 스킬로 점검 한번 해 봐.
나도 알기 쉽게 체크리스트 형식으로 체크된 것과 보완해야 할 것 표시해 봐.

1. /cso 점검 결과를 검토하고 "보완해야 할 것" 목록을 우선순위 순으로 처리한다.

⚠️ 주의: 보안 점검에는 토큰을 아끼지 않는다. 보안 사고(데이터 노출·권한 탈취)는 코드 버그보다 복구 비용이 훨씬 크다. 인텔리전스를 "높음" 또는 "매우 높음"으로 올리고 점검한다.

✅ 확인: 체크리스트에 ✅(통과)와 ⚠️(보완 필요) 항목이 구분되어 출력되면 완료.

Step 8. Worktree 정리 및 마무리

목표: 완료된 병렬 작업 브랜치를 정리하여 저장소를 깔끔하게 유지한다.

1. 모든 구현·리뷰가 완료되면 정리를 지시한다:

다 완성되는 것 같으니 워크트리 정리해 줘.

1. worktrees/ 폴더 내 임시 파일이 제거되었는지 확인한다.

# 수동 정리가 필요한 경우
git worktree list
git worktree remove worktrees/mvp

✅ 확인: git worktree list에서 메인 브랜치만 남으면 완료.

5. 적용 사례 (공신력 오픈소스 5가지+)

하네스 엔지니어링과 동일한 "에이전트 제약·검토 게이트·재사용 가능 구성 단위" 패턴을 실제 프로젝트에서 확인할 수 있는 오픈소스 레포지토리:

6. 핵심 원리

원리 1. 구조가 품질을 결정한다

에이전트의 능력치(모델 크기)보다 에이전트에게 주어지는 제약·예시·검토 게이트가 최종 산출물 품질을 더 크게 결정한다. 동일한 GPT-5.5 모델이라도 하네스 없이 자유롭게 실행하면 결과물이 매 실행마다 다르고, 하네스를 적용하면 일관된 패턴으로 수렴한다.

원리 2. 파일이 기억을 대체한다

컨텍스트 압축으로 에이전트의 "기억"이 손실되더라도, docs/ 폴더의 설계 문서·실수 목록·체크리스트는 파일로 영속된다. 에이전트를 신뢰하는 대신, 파일 시스템에 저장된 구조화된 문서를 신뢰하는 것이 하네스 엔지니어링의 실용적 결론이다.

7. 변형·확장

다른 AI 코딩 에이전트와의 호환성

AGENTS.md 표준 다중 에이전트 활용

agents.md 표준 (Linux Foundation Agentic AI Foundation, 60K+ 오픈소스 레포 채택)에 따라 AGENTS.md를 최상위에 두면, Claude Code·Codex CLI·Cursor·Aider 등 여러 에이전트가 동일 SSOT를 공유한다. 이를 통해 에이전트를 교체하더라도 하네스 구조가 유지된다.

8. 다른 도구·접근과의 비교 (3-way)

9. 한계·트레이드오프

1. 토큰 비용 급증 — Superpowers는 단일 태스크에서도 브레인스토밍·계획·구현·리뷰·컴파운드 단계를 각각 LLM 호출로 처리한다. 일반 대화 대비 3~8배 토큰을 소모하므로, 간단한 1회성 수정에는 오버엔지니어링이 될 수 있다.

2. 환경 의존성 — 하네스는 특정 에이전트 플랫폼(Codex 데스크톱 앱·Superpowers 플러그인)에 의존한다. 플랫폼 정책이나 플러그인 업데이트로 Skills API가 변경되면 기존 하네스가 동작하지 않을 수 있다. 프로젝트마다 하네스를 새로 구성해야 하는 이유이기도 하다.

3. 컨텍스트 압축 한계 — 컴파운드 엔지니어링으로 실수 목록을 파일에 저장해도, 에이전트가 매번 해당 파일을 올바르게 참조한다는 보장이 없다. 매우 긴 컨텍스트에서 압축이 반복되면 파일 참조 자체도 누락될 수 있다.

10. 최신 권장 패턴 (2026+)

(검증일 2026-05 기준)

Codex CLI + MCP 통합

OpenAI Codex CLI는 MCP(Model Context Protocol) 서버와 연동하여 외부 도구(데이터베이스·API·파일 시스템)를 Skills처럼 사용할 수 있다. 하네스 구성 시 MCP 서버를 통해 에이전트의 입·출력 범위를 명시적으로 제한하는 패턴이 권장된다.

Skill 모듈화

단일 Skills 파일이 아닌, /brainstorming → /writing-plans → /subagent-driven-development → /cso 순서로 Skills를 조합하는 파이프라인 하네스 패턴이 실무에서 재현성을 높인다. 각 Skills를 독립적으로 교체·비활성화할 수 있어 프로젝트 특성에 맞게 조정이 가능하다.

📚 참고: garrytan/gstack의 Compound Engineering 패턴과 Anthropic Building Effective Agents의 워크플로 에이전트 설계를 함께 참고한다.

Subagent 모델 계층화

비용 효율을 위해 상위 모델(GPT-5.5 / claude-sonnet-4-6)은 계획·검토 단계에, 하위 모델은 반복적 구현 태스크에 배치하는 계층화 패턴이 확산되고 있다. 이 패턴은 토큰 비용을 40~60% 절감하면서 품질을 유지한다.

11. 메타인지 자기평가

Step 1. 현재 상태 점검

다음 질문에 솔직하게 답한다: - AI 코딩 에이전트를 사용할 때 매번 다른 결과가 나와 당황한 경험이 있는가? - 에이전트가 생성한 코드를 "그대로 믿고" 배포한 뒤 버그가 발생한 경험이 있는가? - 긴 대화에서 에이전트가 초기 요구사항을 잊어버린 경험이 있는가?

하나라도 "예"라면, 하네스 엔지니어링이 현재 워크플로에 즉시 적용 가능하다.

Step 2. 적용 가능성 평가

Step 3. 점진 적용

1주차: Step 2(Superpowers 설치) + Step 4(설계 문서 SSOT)만 적용. 코드 대신 문서를 신뢰하는 습관 형성.

2주차: Step 5(서브에이전트 TDD) 추가. Git Worktree 병렬 작업 패턴 익히기.

3주차+: Step 6(컴파운드 엔지니어링) + Step 7(CSO 보안 점검) 추가. 전체 하네스 루프 완성.